<html>
<body>
Serializable implementation of the JCR Value interfaces.
<p>
This package contains a simple implementation of the JCR
{@link javax.jcr.Value Value} and {@link javax.jcr.ValueFactory ValueFactory}
interfaces. The implementation has no external dependencies and supports
serialization of Value instances.
</p>
<p>
Note that the Value instances created by this package are not thread safe.
</p>
<h2>Implementation notes</h2>
<p>
This package uses the State design pattern (GoF) to implement the JCR
{@link javax.jcr.Value Value} interface. A Value instance is initially
in a fresh state that gets committed to a stream or non-stream state once
the first value getter method is invoked. After that the Value state is
no longer changed. The state diagram below illustrates the Value states.
</p>
<p align="center">
<img src="doc-files/state.jpg" alt="Value state diagram">
</p>
<p>
The {@link GeneralValue GeneralValue} implementation class acts as the
state context object. It contains a reference to another Value instance that
represents the current Value state. The reference is initially set to
an {@link InitialValue InitialValue} instance that is used to intercept
the first value getter method. When the first method call is made, the
InitialValue instance performs the correct state transition by changing
the GenericValue state reference to a committed Value instance.
</p>
<p>
The committed Value states are implemented by the type-specific classes
{@link StringValue StringValue}, {@link LongValue LongValue},
{@link DoubleValue DoubleValue}, {@link BooleanValue BooleanValue},
{@link DateValue DateValue}, and {@link BinaryValue BinaryValue}.
These classes handle no state transitions, but implement the value
conversion rules defined in the JCR specification.
</p>
<p>
The sequence diagram below illustrates the sequence of actions of
creating a string value, committing it to the stream state, and finally
using it in that state.
</p>
<p align="center">
<img src="doc-files/sequence.jpg" alt="Value sequence diagram">
</p>
<p>
These implementation classes are all package-local and final, and their
behaviour can therefore not be modified externally. The Decorator design
pattern should be used if changes to Value behaviour are needed.
</p>
<h2>About Value equality</h2>
<p>
The current JCR specification (0.16.4) does not define a safe mechanism for
implementing the {@link Object#equals(Object) equals} method in general.
A proper implementation of this method would currently require potential
state changes in the compared Value instances. Thus this package only defines
equality comparisons between Value instances generated by this package and
throws {@link UnsupportedOperationException UnsupportedOperationExceptions}
for more general Value comparisons.
</p>
</body>
</html>
